Excel models

Read this reference to learn the basics of Excel models with Epicenter.

To illustrate the concepts described below, we use a simple savings account model, which you can download here .

Time and Step

For a turn-by-turn project, your Excel model must have these essential elements:

• A one-cell named range called Step containing an integer value. Epicenter will increment this value by one each time your app makes a step.
• A named range called Time. This is a range of cells containing integers. It defines the timeline of the game from beginning to end. The values in the range correspond to the steps of the game.

note

In the downloadable savings account model, the Time range represents months, and the timeline spans one year.

With the savings account model, the app looks at one column for every step, starting with column B.

Access variables

You can reference the named ranges in the Excel model as variables in your Epicenter app.

For example, the savings account model expects the player to enter the total transaction amount for each month in the transactionAmount named range. To create an input for it in the Interface Builder:

1. Select a Text Input element.
2. In the Properties panel on the left, click the Variables drop-down.
3. Select the transactionAmount[Current Step] variable.

Access cell values

The Epicenter JS libraries allow you to access cell values.

To access a single cell value or the values from a range of cells, call the getVariable() function of the Run adapter, passing the range names or the cell coordinates in the variable parameter. See the code examples below.

Retrieve named range values

import { runAdapter } from 'epicenter-libs';

step = await runAdapter.getVariable(
    '0000019975d0aaebd160de2450566846su33', 
    'Step'); // returns the value of the Step named range (a single cell)

balance = await runAdapter.getVariable(
    '0000019975d0aaebd160de2450566846su33', 
    'Balance'); // returns the values of the Balance named range (multiple cells)

Retrieve cell values by coordinates

import { runAdapter } from 'epicenter-libs';

B8_value = await runAdapter.getVariable(
    '0000019975d0aaebd160de2450566846su33', 'B8'); // returns the value of the B8 cell in your model file

B8_to_N8_values = await runAdapter.getVariable(
    '0000019975d0aaebd160de2450566846su33', 'B8:N8'); // returns the values of the B8 to N8 cells as an array

Save variables

To configure Epicenter to automatically save variable values to database, update the variables object in your model context file.

Execute operations

You can execute operations on your Excel model to move the game forward.

Using Interface Builder

The Interface Builder allows you to execute two operations on the model:

• step(): Increments the value in the Step named range of your mode by 1.
• stepTo(step): Step to a specified step. The argument is either the keyword 'END' or an integer value from the Time named range in your model. The model will move to the specified step or to the end of the timeline. If this operation is called repeatedly, the model only moves up to the specified step. Useful for multiplayer games.

To configure an operation call in Interface Builder:

1. Select a button control on a page.
2. In the Properties panel on the left, select the required operation.

Using the JS libraries

If you develop your app UI with the Epicenter JS libraries, you can call more operations on your Excel model:

• stepBack(step): Goes back to the specified step. The argument is either the keyword 'START' or an integer value from the Time named range in your model.
• download(): Download a spreadsheet with all the current model variable values.
• recalculate(): Forces all variable values to be recalculated when a cell value changes in the model file.

To call an operation on a model, use the operation() function of the Run adapter.

Code example: Go back to step 4.

import { runAdapter } from 'epicenter-libs';

const result = await runAdapter.operation(
    '0000019975d0aaebd160de2450566846su33', // the Run key
    'stepBack',                             // the operation name
    [4]                                     // the operation parameter
);

What's next?

To learn how to create an Epicenter app based on your Excel model, follow this tutorial.